Reasonable care (despite what you might think!) has
in fact been taken in the preparation of this
document and the software described herein. However, the
author makes no representations or warranties regarding the
fitness of the software for a particular purpose or its
merchantibility; moreover, the author assumes no responsibility
or liability for errors, omissions, bugs, or inaccuracies in
either the software or its documentation. Said software and
documentation are provided “as is" and are subject to revision
without prior notice.
TRADEMARKS:
Acrobat is a trademark of Adobe Systems, Inc. Code Warrior is a
trademark of Metrowerks, Inc. PowerMac and Macintosh are trademarks
of Apple Computer. Other trademarks and trade names are the property
of their respective holders.
UPDATES:
Updates will be posted at <pre>http://www.acroforms.com</pre>.
<!!>
<B> <FONT COLOR=#dddddd><RECT 0 0 800 900 >
<FONT COLOR=#006333>
Author: </B>
Kas Thomas
<B>
Developed using:</B>
Metrowerks Code Warrior Pro 5
PDFLib by Thomas Merz (tm@muc.de)
BBEdit Extension Interface SDK v7.0
(from http://www.barebones.com)
<B>
This documentation created using:</B>
BBEdit v5.0
PDF-Blit™ v1.02
<!!>
<FONT COLOR=#220000>
<h2>What’s New in 1.02</h2><FONT COLOR=#000000>
The major bug fixes are as follows.
First, the <b>transitions effects drop-down menu </B></b> should now work properly for all users. This has been a much-requested feature and is obvously a very important bit of functionality in the sense that <b>PDF-Blit gives you greater control over page transition effects than the full commercial version of Acrobat</b> (at least in version 4.0). If you haven't tried applying page transition effects to your documents, try it! Do it immediately! You won't believe how much extra impact it adds to PDF documents.
Secondly, the font dropdown menu now works more reliably as well.
Also, the lockups that users of BBEdit Lite were experiencing should no longer happen, since PDF-Blit now checks for what version of the BBE callback suite is present before using it. (Duh!) But do note one thing. If you use a Lite version of BBEdit, PDF-Blit may not be able to get Acrobat Reader started for you, automatically. This bit of functionality is definitely available when PDF-Blit is used with the full version of BBEdit, though.
And finally, the \<BR> tag is no longer erroneously interpreted as \<B>! (Sorry. That was really stupid of me!) The HTML interpretation features are still rather rudimentary, so bear with us.
Don't expect the world here. This is a work-in-progress, basically developed in my spare time. You should expect some rough edges!
And there certainly still are some. For example: Every once in a while, PDF-Blit causes BBEdit to simply quit cold, for no reason (apparently a memory leakage condition ?), which I'll hopefully figure out a fix for by the next release... But I ask you to be patient. I am not terribly upset by little things like an occasional need to restart the host program. Heck, this kind of behavior is standard for the likes of Netscape Communicator 4.62, so...
As always, be sure to return to <b>www.acroforms.com</b> frequently to check for upgrades. Also bookmark my daily column at <b>http://www.acroforms.com/cgi-bin/rage.pl</b>, where you will find news, tips, gossip, opinions, arm-waving, JavaScript and Perl hacks, insider news on PDF and SVG, and all kinds of other good stuff, on (as I say) a <b>daily</b> basis. Don't miss out!
<!!><FONT COLOR=#220000>
<h3>What Is PDF-Blit™?</h3><FONT COLOR=#000000>
PDF-Blit is an extension, or plug-in, for BBEdit (and BBEdit Lite), the text editor marketed by Bare Bones Software. The plug-in is designed to give a PDF export capability to BBEdit, thereby letting BBEdit users create attractive, richly formatted documents without having to use Distiller, Acrobat, or any other PDF authoring software. With PDF-Blit, you can output Portable Document Format files directly from BBEdit.
<FONT COLOR=#220000>
<h3>Features</h3><FONT COLOR=#000000>
PDF-Blit will let you create very attractive, colorful documents directly from BBEdit, in your choice of serif (Times-Roman), sans-serif (Helvetica), or fixed-width (Courier) typeface, at any point size, and with any line spacing. Not only that, but you can use italics, boldface type, headings, and colored type freely throughout your document (by appropriate use of HTML-style tags; see further below). This manual, for example, was created using BBEdit and PDF-Blit™. In fact, the raw text version of this document is included in the PDF-Blit™ distribution files, so that you can see how various tags were used to achieve various effects in this document.
PDF-Blit™'s powerful capabilities include:
• Choice of 12 default typefaces.
• Fonts in any point size, including fractional values.
• Leading (line spacing) of any magnitude, including fractional values.
• Text color can be varied on the fly.
• Typeface can be styled (italics, boldface, bold italics) on the fly.
• 6 heading sizes.
• Customizable tab width.
• Customizable character width. (Fonts can be condensed or expanded in one-percent increments.)
• Text justification option.
• User can set margins on all 4 edges of page.
• Choose from 7 page-transition effects (box-zoom, split, blinds, glitter, dissolve, wipe, and replace).
• Auto-page-numbering can be turned on or off.
• User-customizable header can be enabled/disabled.
• PDF file can be auto-opened in Acrobat Reader.
• HTML tags interpreted (see below).
• User control over PDF Document Info fields (Author, Title, Keywords).
<FONT COLOR=#FFFFFF><!!>
And now... <FONT COLOR=#220000>
<h3>Installation</h3><FONT COLOR=#000000>
You can install PDF-Blit by dragging it into your BBEdit Plug-Ins folder. The extension will load automatically when you start BBEdit. You should see “PDF-Blit...” in the Tools menu when BBEdit is running. (It will be grayed out until you have a document open, however.)
<FONT COLOR=#220000>
<h3>Basic Operation</h3><FONT COLOR=#000000>
You can output a PDF version of any file that's open in BBEdit's foremost window simply by choosing “PDF-Blit ...” from the Tools menu and clicking OK when the PDF-Blit dialog appears. Your original document will not be altered in any way. A new file, with the same name as the current document, but with “.pdf" appended to the name, will appear in the BBEdit default folder (the folder BBEdit is in). The new file will be a PDF file (filetype 'PDF ' and creator 'CARO') conforming to Version 1.3 of the PDF specification, suitable for viewing by Acrobat Reader 3.0 or higher.
<FONT COLOR=#220000>
<h3>Preferences</h3><FONT COLOR=#000000>
You can set various user preferences in PDF-Blit's setup dialog, which appears every time PDF-Blit is launched. The settings you choose here will persist across BBEdit sessions. That is, each time you launch PDF-Blit, you will see the same settings that you chose the <i>last</i> time you used PDF-Blit. Your settings will not be lost, even after you quit BBEdit.
<!!>
<FONT COLOR=#440000>
<h1>Advanced Options</h1><FONT COLOR=#220000>
<h3>Default Typeface</h3><FONT COLOR=#000000>
A drop-down menu allows you to select from 12 default typefaces for your document. The typefaces are Helvetica, Helvetica Bold, Helvetica Oblique, Helvetica Bold Oblique, Times-Roman, Times Bold, Times Oblique, Times Bold Oblique, Courier, Courier Bold, Courier Oblique, and Courier Bold Oblique. If you have left the “Interpret tags" checkbox unchecked (see below), the typeface that you select from the drop-down menu will remain the sole typeface used throughout your document. <i>If you wish to make use of bold, italics, or bold-italics at various places throughout your document, you need to check the “Interpret tags" checkbox and choose one of the three basic typefaces-Helvetica, Times-Roman, or Courier-as your default typeface.</i>
<FONT COLOR=#220000>
<h3>Point Size</h3><FONT COLOR=#000000>
You can choose any point size for the text in your document, including fractional values such as 9.8 or 13.6. For most documents, a default point size of 10 to 14 points works best.
<FONT COLOR=#220000>
<h3>Leading</h3><FONT COLOR=#000000>
Leading refers to the vertical spacing between lines of text. You can supply any leading value you want, but for most types of documents the leading value should be close in magnitude to the point size of the text. Use a higher leading value for greater space between lines; a lower value for more tightly packed lines. (A leading value that is three to four times the point size of the type will give your document a “double-spaced" look.)
<FONT COLOR=#220000>
<h3>Tabs</h3><FONT COLOR=#000000>
You can tell PDF-Blit how many spaces to insert for each Tab in your document. A value of from 3 to 6 works good for most documents, although if you are setting up special tables, you may want to try other values.
<FONT COLOR=#220000>
<h3>Character Width</h3><FONT COLOR=#000000>
The default value for character width is 100, meaning 100% of normal width. For condensed type, enter a value smaller than 100. (For example, a value of 75 means every character in your document will be 75% of normal width.) For expanded type, use a value greater than 100. Note that the value you supply here applies globally to every character in your document.
<FONT COLOR=#220000>
<h3>Transition Effect</h3><FONT COLOR=#000000>
A second drop-down menu lets you choose from seven different page-transition effects that will take place in Acrobat Reader as you page through an open PDF document. The effects apply globally to every page in a document. The default effect is <b>replace. Box, split, wipe, and blinds</B> implement familiar cinematic transition effects.
PDF-Blit allows you greater control over transition effects than the full commercial version of Acrobat 4.0 does! This feature alone makes PDF-Blit™ a very powerful tool.
<FONT COLOR=#220000>
<h3>Page Numbering</h3><FONT COLOR=#000000>
By checking the “Show Page Numbers" checkbox in PDF-Blit's setup dialog, you can make PDF-Blit number your document's pages for you. Page numbers will appear (in the default typeface) in the upper righthand corner of every page. <i>Note: To position the page number exactly where you want it, experiment with different Top Margin settings (below).
<b>Tip: To keep a page number from appearing on the title page (first page) of your document, create a page-sized white rectangle (see below) on that page, before any text. The first page is numbered before the rectangle is drawn, which means that you can overpaint the first page number with white by using the big-white-rect technique. </b></i>
<FONT COLOR=#220000>
<h3>Header Lines</h3><FONT COLOR=#000000>
You can make PDF-Blit™ print up to three header lines in the upper left corner of every page, by default, just by checking the “Show Headers" checkbox and entering text in the Author, Title, and Keywords text-edit areas in the lower portion of the setup dialog. Whatever you type in the Author box will appear as the first line of your header. Whatever you type in the Title area will appear on a second header line, and whatever you type in Keywords will appear on a third header line. To make any header line not appear, just delete all text from the appropriate text-edit box. (No header will appear at all, of course, unless you have checked the “Show Headers" checkbox.)
<FONT COLOR=#220000>
<h3>Justify Text</h3><FONT COLOR=#000000>
You can make PDF-Blit justify your document's text (flush right and flush left) by checking the Justify checkbox. But in order for justification to work properly, your document <i>must not contain hard returns at the end of every line.</i> Carriage returns must occur ONLY at paragraph endings, not at line endings. Fortunately, this is BBEdit's default behavior. (Soft-wrapping of text onscreen does not place hard returns in the actual document. So you can leave “soft wrapping" enabled.) Documents retrieved from DOS or Windows systems may not justify until you remove all the carriage returns and linefeeds from the line endings. Ditto for e-mail messages, which may contain hard returns at the ends of lines.
<B>Important:</b> In this version of PDF-Blit™, you cannot enable tag interpretation and text justification at the same time. This is because PDF-Blit™ does not (currently) cache whole lines of text when formatting is enabled. Therefore, you can have formatting (italics, bold, headings, colored type, etc.), or you can have text justification, but not both. If there is sufficient interest, we will fix this in a future upgrade. In the meantime, to enable the “Interpret Tags" checkbox, uncheck the Justify checkbox, and vice versa.
Note: To control column width when justification is enabled, set your left and right page margins appropriately. In this version of PDF-Blit™, the ability to create multiple columns of justified type on the same page is not implemented. Again, if there is sufficient interest, we will implement this in a future upgrade.
<FONT COLOR=#220000>
<h3>View in Acrobat</h3><FONT COLOR=#000000>
By checking the “View in Acrobat" checkbox, you are telling PDF-Blit to launch Acrobat or Acrobat Reader (whichever is present on the BBEdit default disk) and display your just-created PDF file in Acrobat when PDF-Blit is done. Of course, sufficient free memory to run Acrobat must exist in order for this to work properly. <i>After Acrobat (or Reader) launches, your document will come to the front and Acrobat will be the active application. BBEdit will continue to run in the background.</i>
If you do not wish to see your PDF document open in Acrobat, leave “View in Acrobat" unchecked.
<FONT COLOR=#220000>
<h3>Interpret Tags</h3><FONT COLOR=#000000>
PDF-Blit™ v1.0 has a rudimentary built-in ability to interpret HTML tags. But not <i>all</i> HTML tags. The tags that are supported at this time include:
• \<I> ... \</I> for italics.
• \<B> ...\ </B> for boldface.
• \<H1> thru \<H6> ... \</H1> thru \</H6> for headings.
• \<PRE> and \</PRE> for constant-width preformatted text (Courier).
• \<FONT COLOR=#RRGGBB>, where RRGGBB represents hex values for red, green, and blue color components.
Examples:
<I>This shows the use of \<I> for italics.</i>
<B>This shows the use of \<B> for boldface.
<I>This shows the use of \<B>\<I> for boldface italics.</I></B>
<pre>This shows the use of \<pre> for preformatted text.
<B>This shows preformatted boldface text via \<pre>\<B>.
<I>And of course you can combine tags</i> in almost any</pre> manner </b>you want.
<h1>Heading \<h1> looks like this.</h1>
<h2>Heading \<h2> looks like this.</h2>
<h3>Heading \<h3> looks like this.</h3>
<h4>Heading \<h4> looks like this.</h4>
<h5>Heading \<h5> looks like this.</h5>
<h6>Heading \<h6> looks like this.</h6>
<I><B>All other HTML tags are ignored and will not print (unless escaped as described in Note 4 below).</b></i>
Note 1: The HTML tags are not case-sensitive.
Note 2: Headings are always Times Bold.
Note 3: Style tags (bold, italics, etc.) should not be nested with heading tags (h1, h6, etc.).
Note 4: When tag interpretation is enabled, the angle brackets will not print unless they are escaped with a backslash, as in<b> \\<.</b>
<FONT COLOR=#000000>
<h4>Additional (Non-Standard) Tags</h4>
In addition to the standard HTML tags listed above, PDF-Blit™ recognizes some tags of its own:
• Use \<!!>to force a page break.
• Use \<#30>to force the file to end abruptly.
The former is useful when you are formatting a long document and need to be sure that a short section ends on a particular page.
The latter marking is useful as a workaround for a PDF-Blit™ bug that occasionally results in garbage characters at the very end of a file. By using \<#30> at the end of a file, you can prevent garbage characters from ever showing up.
<h4>Graphics Capability</h4>
PDFBlit™ incorporates one vector-graphics facility, for drawing rectangles. The special tag that invokes this facility is:
\<RECT XX YY WW HH>
where XX and YY are numbers representing the coordinates for the lower left corner of the rectangle and WW and HH are numbers representing the width and height, respectively, of the rectangle. <I>Note that all rectangles are solid-filled with the current text color.</i>
<b>Important:</b> In PDF space, the lower left corner of a page is the origin. The 'y' axis increases in the upward direction. Thus, to create a rectangle that covers an entire letter-sized page, you would write<b> \<RECT 0 0 612 792>.</b>
<!!>
<FONT COLOR=#220000>
<h3>Setting Margins</h3><FONT COLOR=#000000>
You can set the margins for all four edges of your page. The units are in printer's points (72 points to the inch). If you want half-inch margins left and right, set the left and right margin values to 36. For a two-inch margin at the top of the page, use a value of 144. And so on.
<FONT COLOR=#220000>
<h3>Author</h3><FONT COLOR=#000000>
The Author text-edit box lets you attach Author information to your PDF document. This information is seen in Acrobat Reader when the user chooses the “Document Info...” command. <I>Note: Any text you type here will also show up in the header on each page of a document if you have enabled “Show Headers.” </I>
<FONT COLOR=#220000>
<h3>Title</h3><FONT COLOR=#000000>
The Title text-edit box lets you attach Title information to your PDF document. This information is seen in Acrobat Reader when the user chooses the “Document Info...” command. <I>Note: Any text you type here will also show up in the second line of the header on each page of a document if you have enabled “Show Headers.” </I>
<FONT COLOR=#220000>
<h3>Keywords</h3><FONT COLOR=#000000>
The Keywords text-edit box lets you attach Keywords information to your PDF document. This information is seen in Acrobat Reader when the user chooses the “Document Info...” command. <I>Note: Any text you type here will also show up in the third header line on each page of a document if you have enabled “Show Headers.” </I>
<h1>A Short PDF-Blit™ FAQ</h1><FONT COLOR=#000000>
<b>How can I create a colored background for a page?</b>
In addition to enabling tag interpretation (see above), you must do three things:
1. Set the rectangle's color, by writing \<FONT COLOR=#RRGGBB> where RRGGBB are the hex values for the color components.
2. Create a rectangle covering the whole page. For example: \<RECT 0 0 700 800>.
3. Make sure you have inserted the foregoing code <b>prior to</b> any text that is to appear on the page. Otherwise, the rectangle will overwrite the text and you won't see any text. Also make sure that after you have created the rectangle that you reset the text color to a different color, say black (an RGB value of #000000). Otherwise, your text will be printed over the rectangle in the rectangle's own color, which of course will render the text invisible.
<B>Where can I find out about upgrades to PDF-Blit™?</b>
Visit <B>www.acroforms.com</b> on a regular basis. We do not operate a mailing list at present.
<B>Is source code available for PDF-Blit™?</b>
No, although a bare-bones framework (so to speak) for the code appeared in a late-1999 issue of <I>MacTech</i>. Go to <B>www.mactech.com</b> for details.
Code for the PDF-generating portions of PDF-Blit™ came from Thomas Merz's excellent PDFLib library. For that, visit <B>www.pdflib.com.</b>
<B>I would like to be able to put thin horizontal rules on a page. Is there a way to do this?</b>
Create one-pixel-deep rectangles at the positions where you want rules to appear. Remember, PDF-Blit™ will let you position rectangles with pixel accuracy. It may take you awhile to fit the text around your “rects” but with a little experimentation you should be able to achieve some nice effects.
<B>Can I print white text on a grey background?</b>
But of course! Just draw a gray rectangle (see above) in the appropriate place(s) and then specify a text color of #FFFFFF with a FONT tag. (But be sure to change the font color back to a non-white color later, after you're done drawing over the colored rect.)
<B>My headers and page numbers look awfully close to the top of the page. Is there a way to change this?</b>
Set your top margin to a more generous value (for example, 150).
<B>Some lines of text are going off the right edge of the page. Is there a way to keep this from happening?</b>
Set your right margin to a higher value. Or enter hard returns in your “problem lines.” But remember that if you change point sizes or typefaces, your lines may reflow in an unexpected manner.
<B>Is there a way to change the typeface or size or placement of the headers or page numbers?</b>
Not at this time. Sorry.
<B>Can I use condensed type? Will it affect text justification or right-hand page margins in any way?</B>
You can vary character widths in the setup dialog. Entering 50 (for 50% of normal) will give you very VERY tightly condensed (skinny) letters. A more tasteful value would be 85%. But in any case, text justification is not affected. Your text should justify normally (to the margins you selected) with character width values other than 100.
<B>Will PDF-Blit™ hyphenate words to achieve better justification?</b>
No attempt is made to hyphenate words. Even so, the justification should look pretty good, because we use a combination of word spacing adjustments, character spacing, and character width adjustment to achieve justification. The lack of hyphenation shouldn't be a factor in most cases. The only time it might be a factor is when the column width is small relative to the point size of the type. In that case, you should either turn justification off or use smaller type (or smaller margins).
<B>Is there any limit on the number of pages I can have in a document?</b>
No.
<B>Will I run out of memory if I try to convert a large document to PDF?</b>
No, you shouldn't. Large or small shouldn't matter, since the document is written to disk progressively as it is created. It isn't cached in memory.
<B>Sometimes when I make changes to a document and re-render it as PDF, the changes don't show up in the open document in Acrobat Reader.</b>
You have to close the old PDF document in Reader before re-rendering a new version of it. Otherwise, Reader still shows you the old version.
<B>Can I save my PDF document to a different directory or folder?</b>
Not presently. Right now, the PDF file is automatically written to the same folder where BBEdit resides.
<B>Can I somehow insert hidden signatures or copyright notices inside my PDF document?</b>
Yes. To some degree, that's what the Author, Title, and Keyword fields of the setup dialog are for. Text you type there will be embedded in the PDF document, visible only when the user selects “Document Info...” in Acrobat.
<B>When I begin a line with a heading, using \<h6> for example, I get an extra carriage return ahead of that line that I don't want. What can I do about it?</b>
This is a known bug (or feature, depending). You can try this workaround: Immediately before the heading, type a blank space. When you convert to PDF, the space will be removed, the heading will be flush-left, and the extra carriage return will no longer be there.
<B>PDF-Blit doesn't seem to like for a line to begin with a space. I notice it removes spaces at the start of a line. What can I do about this?</b>
Type Option-Space, instead of space, at the start of a line if you really intend to begin a line with a space, for example if you're trying to manually align preformatted text. Option-Space will solve the problem.
<B>I would like to convert my C or JavaScript code listings to PDF, using PDF-Blit, but when I do it, all of my indenting is lost.</b>
Read the last question and answer. A good workaround for you, if you have highly indented files, would be to use BBEdit's global Find and Replace feature to search on all carriage returns (which is the code '\\r') and replace them with <b>backslash-r-Option-space.</b> This means when you are done, every single line will start with a <i>noncollapsible space, </I>and your document's indenting will be preserved throughout the document.
<B>Every once in a while, I'll go to output a document and all of a sudden I'll find that the default font has changed, by itself! What's going on?</b>
It doesn't change by itself. What happens is that if you <b>end</b> a tagged text file before you've closed the last tag, then whatever typeface you were in when the file was closed becomes your new default typeface. The answer should be obvious: Always close your tags. That means if you use \<pre>, you should later close it with \</pre>, especially if it's the last tagged area in the file. Leaving off the closing \</pre>tag will change your default typeface to Courier, possibly causing you to think Acrobat Reader can't find a needed font resource.
<B>Sometimes, when I am outputting a document in Helvetiva Bold, halfway through a page the type will change to plain Helvetica. For the rest of the page, I will get non-bold, even though I chose Helvetica Bold as the default typeface in the setup dialog.</b>
If you truly want Helvetica Bold to be globally applicable all throughout the file, turn HTML tag interpretation off. That way, your typeface selection will remain in effect no matter what! Unfortunately, if you enable HTML tag interpretation, it is possible for you to unwittingly "unbold" a section by using \<b> and \<\b> tags around a word or phrase. This is because PDF-Blit slavishly adheres to whatever tag instructions you call out. We could make PDF-Blit smarter about how it interprets tags, but that would take a bit of work and frankly we'd rather devote that kind of effort to supporting other types of features. So if you are truly intent on enforcing the use of one particular typeface throoughout a document, turn off HTML tag interpretation. That's the only sure way to get the job done. (Otherwise, cleverly reinsert boldface or other tags as necessary in your text, to keep styling the way you intended it.)
<B>Do I need to credit PDF-Blit or PDFLib, Thomas Merz, Aladdin, etc. in any documents I create with PDF-Blit?</b>
No. Not as far as we're concerned.
<B>Can I put hypertext links in my PDF document using PDF-Blit™?</b>
Not presently. This is just one of many features we'd like to add to PDF-Blit™ someday. If you have a feature you'd like to see added, contact the author at <B><pre>kt@acroforms.com.</pre></b>
<B> Is there any truth to the rumor that you are working on a plug-in called SVG-Blit?</b>
Yes and no. We are considering whether to try to give BBEdit some sort of primitive SVG output capability via a plug-in. (SVG is short for Scalable Vector Graphics, in case you've been on another planet.) The SVG-Blit plug-in, like BBEdit itself, would be restricted to text output only, not graphics. The main benefit of such a plug-in is that you could use it to achieve a variety of text-justification and other typographic effects using the base-14 fonts, very easily, without buying a high-end software package or trying to do text compositing in Adobe Illustrator (which has a good SVG-output plug-in but is a terrible environment for producing text). It will be a long time before decent text justification is available in the SVG format. Our thinking is that a BBEdit plug-in could fill the gap for a while.
And in the meantime, tell your friends about us! Remember the URL:<FONT COLOR=#880000> <pre>www.acroforms.com.</pre>
